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PREFACE 


OBJECTIVE 


This manual explains how to use VAX DEC/CMS (Code Management System). It is an 
introductory level book with examples that illustrate basic techniques. 


INTENDED AUDIENCE 


This manual is intended for software engineers, technical writers, and managers working 
. on a wide range of software projects. 


Version 2 of DEC/CMS runs only on the VAX/VMS operating system Version 4.0 or later. 


STRUCTURE OF THIS DOCUMENT 


The User's Introduction to VAX DEC/CMS is divided into seven chapters, one appendix, 
and a glossary. 


e Chapter 1, CMS Concepts, describes how CMS facilitates the software development 
cycle and briefly explains how to use CMS. | 


e Chapter 2, Building a CMS Library, describes how to set up a CMS library and also 
how to load files into the library. 


e Chapter 3, Using a CMS Library, describes the basic commands that you use to 
retrieve and replace library files. 


e Chapter 4, CMS SHOW Commands, explains how you can use CMS commands to get 
information about the contents and the history of a CMS library. 


e Chapter 5, The Evolving CMS Library, describes how to use CMS to track concurrent 
development. 


e Chapter 6, Project Organization with CMS, describes how to use CMS to organize a 
software project. 


e Chapter 7, Additional CMS Commands, describes commands that provide additional 
functions. 


e Appendix A, Notes on Using CMS Libraries, contains general information that is use- 
ful in understanding how CMS works. 


e The Glossary defines important terms. 


ASSOCIATED DOCUMENTS 


e The VAX DEC/CMS Reference Manual (Order No. AA-L372B-TE) provides detailed 
information about CMS concepts and commands. 


e The VAX DEC/CMS Callable Interface Manual (Order No. AA-Z340A-TE) contains 
information about using the DEC/CMS callable routines. 


e Installing VAX DEC/CMS (Order No. AA-Z338A-TE) supplies the instructions for 
installing CMS on a VAX/VMS system. 


e The VAX DEC/CMS Pocket Guide (Order No. AV-L374A-TE) areyiia concise infor- 
mation about CMS commands and callable routines. 


CONVENTIONS USED IN THIS DOCUMENT 


Convention Meaning 
[] Square brackets indicate that the enclosed item is optional. 


A horizontal ellipsis indicates that the preceding item(s) can be 
repeated one or more times. 


$ CMS SHOW YERSION Interactive examples show system output (prompt characters and 
output lines) in black type. All lines that you enter are printed in 
red type. 


element A term that appears in italics is defined in the Glossary. 
Unless otherwise noted: 
e All numeric values are represented in decimal! notation. 


e You terminate a command by pressing the RETURN key. 
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Chapter 1 


CMS Concepts 


DEC/CMS (Code Management System) is a program library system for software develop- 
ment and maintenance. DEC/CMS (also referred to as CMS) stores source files in a library, 
keeps track of changes made to these files, and records user access to the files in the librar- 
ies. In addition, CMS supplies two ways to organize files within a library; these formal 
mechanisms for library organization provide a focus for system design. 


This chapter describes the basic CMS functions. The commands that you use to build and 
then use a CMS library are described in subsequent chapters. This chapter also describes a 
hypothetical project that uses CMS. (Examples throughout this manual refer to this 
project.) 


1.1 Overview of DEC/CMS 


CMS operates as an online librarian for a project. While you perform the normal functions 
of program development, modification, and testing, CMS keeps track of your files. After 
you place your programs in a CMS library, you can retrieve the programs to modify and 
test them in your own directory. You then replace the modified programs in the library for 
safekeeping. Also, you can look up the history of every program in the library, because 
CMS maintains its own records. 


CMS is available at the system command level; commands to CMS are similar to DCL com- 
mands (such as EDIT, COPY, and SET). You can also use CMS at the subsystem level; once 
you invoke the CMS image, you can execute any number of CMS commands while remain- 
ing within the CMS subsystem. 


CMS does its job without imposing unnecessary restrictions on project members. You can 
do all program modification, editing, testing, and development in the familiar VAX/VMS 
environment. You use CMS to perform the following operations: 


e Place a program in the library (Chapter 2). 


e Copy a program from the library to your current default directory and mark the 
library copy as reserved by you (Chapter 3). 


e Return a modified program back to the library (Chapter 3). 
e Retrieve a copy of a program from the library for read-only purposes (Chapter 3). 
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e Display a list of library programs (Chapter 4). 

e List all versions of a library program (Chapter 4). 

e Display the library status or history (Chapter 4). 

e Control concurrent modifications to the same program (Chapter 5). 
e Create specific sets of programs within a library (Chapter 6). 

e Compare two ASCII files in your default directory (Chapter 7). 

e Compare two versions of a program within a library (Chapter 7). 


A CMS library can store an ASCII file that was created by a text editor such as EDT or 
SOS. However, the files you store in the library should be ASCII files that are unlikely to 
change completely in each iteration. (See Appendix A for a discussion of library storage.) 
Usually, text and source files are the project elements that require tracking. 


NOTE 


Use only CMS commands to access CMS libraries. You are responsible for the 
types of files in the library; a file must be sequential and cannot have the same 
characteristics as a binary file. You are also responsible for the method of put- 
ting files in the library and the method of manipulating them in the library; 

_ files that have been put in the library using non-CMS commands may eventu- 
ally be deleted by CMS. In general, the integrity of a library is not assured if it 
has been changed using means other than CMS. 


1.1.1 Library Elements 


An element is the basic structural unit in a CMS library. An element consists of one ASCII 
file. You create and name an element when you transfer a file from your current default 
directory to a CMS hibrary. 


1.1.2 Making Changes to a Library Element 


After you have created an element in a CMS library, you reserve the element in order to 
make changes to it. When you reserve an element, CMS places a copy of the element file in 
your current default directory. You can then edit, compile, test, and debug as usual. When 
you are ready, you replace the element in the library, and CMS stores the changes that 
have been made. 


When you create an element and place it in a CMS library for the first time, CMS creates 
generation 1 of that element. An element generation represents a phase in the development 
of that element. Each time you reserve and replace an element in the library, CMS creates 
a new generation. You can recreate any phase in the development of an element by retriev- 
ing the appropriate generation. 
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CMS numbers the new generations in succession. A CMS generation number is not to be 
confused with the version number that VAX/VMS assigns to directory files; file version 
numbers have no significance to CMS. CMS ignores the number of work sessions done 
outside the library, and assigns a new generation number only when the element is 
returned to the hbrary. 


1.1.3 Reserving and Replacing an Element 


Example 1-1 shows how you can use CMS in the course of program development. 


$ CMS RESERVE TEST1.FOR 

~Remarks check for non-Printing chars 

ZCMS-S-RESERVED+ generation 1 of element TESTi.FOR reserved 
¢ EDIT TEST1.FOR 


+ 
‘ 


+ 


$¢ FORTRAN TEST1/DEBUG 
$ LINK/DEBUG TEST1 
$¢ RUN TESTi 


°$ CMS REPLACE TEST1.FOR 

_~Remark: ; 

ZCMS-S-GENCREATED> generation 2 of element TEST1.FOR created 
¢ CMS SHOW HISTORY TEST1I.FOR 


History of DEC/CMS Library _DRAS:CPROGRAMS.LIBRARY] 


2£B8-MAY-1984 15:04:33 
29-MAY-1984 12:24:5 
SO-MAY-15984 18:05:4 


+ 


SHAW CREATE ELEMENT TEST1i.FOR “parameter list test" 
SHAW RESERVE TEST1.FOR(1) “check for non-Printing chars" 
SHAW REPLACE TEST1.FOR(2) “check for non-Printing chars” 


P2 hos 


Example 1-1: Sample CMS Terminal Session 


The first command to CMS (CMS RESERVE TEST1.FOR) directs CMS to retrieve the ele- 
ment TEST1.FOR from the library. CMS responds with the prompt “_Remark:”. This 
allows you to label the transaction with an appropriate remark. After the remark is 
entered, CMS executes the command and places a copy of the file associated with the ele- 
ment TEST1.FOR in your current default directory. 


The series of commands that follow the first library transaction represent commands a 
programmer might use to modify and test the file TEST1.FOR. The next command to CMS 
(CMS REPLACE TEST1.FOR) also allows the programmer to enter a remark for the 
transaction. In this case, no remark is entered. CMS returns the file to the library. The last 
command to CMS (CMS SHOW HISTORY TEST1.FOR) displays information about the 
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element TEST1.FOR on the terminal. Since no remark was entered for the replacement 
transaction, the remark entered for the CMS RESERVE transaction is also logged for the 
CMS REPLACE transaction. 


1.2 Interactive Help 


Information about CMS is available at the terminal. The HELP CMS command provides 
online documentation in summary form for setting up a CMS library and for using specific 
CMS commands. For example, the following command displays information about the 


CMS RESERVE command: 
$ HELP CMS RESERVE 


You can also get help at the subsystem level: 
CMS>HELP RESERVE 


Since VAX/VMS allows abbreviations you need type only enough of a CMS command to 
distinguish it from any other CMS command. 


1.3 Project Planning and Development 


CMS provides two mechanisms for organizing library elements—groups and classes; by 
using groups and classes, you can plan and use your CMS libraries more effectively. Each 
mechanism imposes its own kind of structure on the library, yet they can be used in the 
same library without conflict. The following sections summarize these methods of project 
organization. See Chapter 6 for more information. 


1.3.1 Using Groups for Structural Organization 


Individual modules of code or text exist in a CMS library as elements. CMS allows you to 
combine related elements into a group that you can then manipulate as a unit. For exam- 
ple, you might create a group that contains all modules that process error messages. 


1.3.2 Using Classes for Organization by Milestone 


The second method of organization is to create classes. You use classes to organize your 
library by milestones. 


One approach is to integrate the modules into working versions or “base levels” that 
represent progressive stages in the development of the entire system. A different approach 
might be to establish classes for more localized stages—one class for each stage of coding, 
testing, and integration to be performed for each generation of the element. The way in 
which you use classes is dependent on the structure of your library and the methodology 
that you use for software development. 
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1.4 A Typical CMS Application 


The following story summarizes how the programmers on one project used CMS. Examples 
throughout this manual refer to the experiences that these programmers had using CMS. 


The three-programmer team was developing an analog data sampling program. The team 
members agreed to use CMS, rather than keeping track of project files manually. During 
the design phase, the project members planned the structure of the product and deter- 
mined the basic CMS mechanisms they would use to reflect that structure. The lead 
programmer, Rick Sanchez, created a library directory for CMS access. As they wrote the 
design documentation, the project members put the files for these documents in the CMS 
library. 


When the design phase was finished, Rick put some project files from his current default 
directory into the project library. Then Rick told Glenn Lewis and Sue Kelley the project 
library directory name, and Glenn and Sue added their own working programs to the pro- 
ject library. Now the project files (SYNCHRON.BAS, SAMPLE.BAS, SPEC.RNO, and sev- 
eral others) resided in the library as elements. 


To organize the library elements, the project members created groups to contain selected 
elements. CMS maintained the list of elements contained in each group. After establish- 
_ing the groups, project members were able to manipulate each group of elements as a sin- 
gle unit. 


Once the project library was set up, it was used as a repository for the project programs. 
Each developer had access to all of the library elements, and any work done on a program 
would be recorded and tracked automatically by CMS. When progress on a program 
branched out to an alternate development path, CMS tracked both the original develop- 
ment path and the alternate path. CMS maintained a complete program history of all mod- 
ifications to the original set of programs. 


Rick and Glenn worked on the same program from time to time. When Glenn requested 
SAMPLE.BAS while Rick was working on it, CMS notified him that Rick had it reserved. 
Occasionally Glenn had to ignore the warning and use the same program. When Rick 
replaced the program, CMS reported that Glenn had worked on the program while he was 
updating it. CMS stored these concurrent changes to the program. Any one of the team 
members could use CMS to merge their changes and flag any conflicting modifications 
(changes that affected the same line of the code). 


Although all three programmers used the command file, TIMTST.COM, to test modifica- 
tions to their own programs, TIMTST.COM itself rarely changed. CMS allowed the project 
members to get copies of the command file while protecting the command file from inadver- 
tent modification. 


CMS Concepts 1-5 


When the team was ready to build its first prerelease version of the data sampler, CMS 
aided in specifying the programs in that version (or “base level”). Rick established a CMS 
class to combine specific versions of these programs together and named the class 
BASELEVELI1. By this time, some programs had been modified more than 20 times. Rick 
inserted specific generations (program versions) of each project program in that class so 
there would be no confusion over which generation of a program belonged in the base level. 


Throughout the project the programmers found that CMS helped to define project develop- 
ment and direction more clearly. Each project member could review all library transac- 
tions and associated remarks. In addition, the programmers could selectively review the 
transactions related to a specific aspect of project development. They also discovered that 
CMS functions simplified their work. For example, when Sue was on vacation, Glenn made 
some changes to an element that Sue usually worked on. Later, Sue was able to get line-by- 
line information on the element, indicating which of her planned modifications had 
already been done. Rick found that the CMS history and its remarks could be used as 
reminders of project accomplishments when he wrote his status reports. 


Later Mike Cohen joined the team. His first assignment was to evaluate problem reports 
from field test sites. He found that the CMS annotated listings of the program modifica- 
tions helped him locate recently changed code more easily. When he wanted to know the 
reasons for the changes, Mike referred to the programmer’s remarks that CMS recorded 
when each modification. was performed. 


Now the original developers have moved on to new projects. Mike, however, has chosen to 
stay with the data sampling project, and he has a new programmer to help him with project 
support and enhancements. They still use the project’s CMS library, which now contains 
every line of code written for the data sampler, along with a complete historical record of 
the project. 
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Chapter 2 


Building a CMS Library 


This chapter describes the procedures and CMS commands that you use to set up a CMS 
library. When you establish a CMS library, you create a directory that is to be used only as 
a CMS library. You then define the protection that wil! allow the appropriate people to 
access the library. Once the directory is established, you can direct CMS to initialize the 
library and then place project files in the library. If you do not have to create a library or 
create elements in a library, you can skip this chapter and go to Chapter 3. 


You set up the library in four steps: 
1. Create a directory to contain the CMS library. 
2. Establish the protection scheme for the library. 
3. Initialize the directory as a CMS library. 
4. Store files in the library as elements. 


Once you have created the library, you should use only CMS to access it. _ 


2.1 Creating a Library Directory 


Jse the DCL command CREATE/DIRECTORY to establish a directory to contain a CMS 
ibrary. For example, at the beginning of the data sampler project, Rick set up a CMS 
ibrary subdirectory with the command: 


> CREATE/DIRECTORY CPROJECT.ADSLIBI 


his command created the subdirectory [PROJECT.ADSLIB] for use as the project library 
lirectory on Rick’s default disk. : 


2 Protecting a CMS Library 


>MS does not define any protection scheme for a library directory or any of the files con- 
ained within the library. Thus, you must explicitly define a-‘UIC-based or ACL-based pro- 
ection scheme for your libraries. 
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Rick wanted Glenn and Sue, who also are in his user identification code (UIC) group, to 
have access to the library files at will. After he created the subdirectory [PRO- 
JECT.ADSLIB] for use as the CMS library, he used the following commands to set the 
required protection: 


$¢ SET PROTECTION=(S:RWEsO:RWEsG:RWE) CPROJECTIADSLIB.DIR 
$¢ SET FILE/ACL=(DEFAULT_PROTECTION;5:RWD;O:RWD>G:RWD) CPROJECTIADSLIB.DIR 


The DCL command SET PROTECTION specifies that system, owner, and group members 
have the standard read, write, and execute access to the [PROJECT.ADSLIB} directory. 
The DCL command SET FILE/ACL specifies that system, owner, and group members are 
allowed read, write, and delete access to all new files created in the library directory. 


See the VAX DEC/CMS Reference Manual for more information about protecting CMS 
libraries. 


2.3 Creating a CMS Library 


The CMS CREATE LIBRARY command creates CMS control files in a directory. Once you 
initialize a directory with CMS data structures, CMS uses that directory to locate and 
store project files. All commands to the CMS system automatically refer to this directory 
until the end of the terminal session, or until you specify a different library with the CMS 
SET LIBRARY command (see Section 3.1). 


For example, Rick initialized the subdirectory, ADSLIB, with the following command: 


¢ CMS CREATE LIBRARY CPROJECT.ADSLIBI 
_Remark: a/d data sampling library 
ZCMS-S-CREATED;, DEC/CMS library DRAS:CPROJECT.ADSLIB] created 


Then, with the library created, protected, and initialized, he was ready to use CMS and 
place project files in the library. 


2.4 Placing Project Files in the CMS Library 


The CMS CREATE ELEMENT command instructs CMS to move a file from your current 
default directory into the library. (When CMS places a file in the library, all copies of that 
file are deleted from your current default directory. You can use the /INPUT qualifier to 
direct CMS to use a file from a directory other than your current default, in which case 
CMS deletes the file from the specified area.) An element name is the file name and type of 
the file specified in the CMS CREATE ELEMENT command. Every element in the CMS 
library must have a unique name. 


On the data sampler project, Rick moved five files into the library. He gave CMS the follow- 
ing CMS CREATE ELEMENT commands: 
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$¢ CMS CREATE ELEMENT SPEC.RNO 

~Remarks ad samplings functional specificatricn 
ZCMS-S-CREATED>» element SPEC.RNO created 

$ CMS CREATE ELEMENT ADCONVERT.BAS 

-~Remark: analog to digital conversion routines 
ZCMS-S-CREATED: element ADCONVERT.BAS created 
$ CMS CREATE ELEMENT SAMPLE.BAS 

-Remark: Sampling module 

ZCMS-S-CREATED:s: element SAMPLE.BAS created 

$ CMS CREATE ELEMENT SYNCHRON.BAS 

-Remarks Synchronization routines 
ZCMS-S-CREATED» element SYNCHRON.BAS created 
$ CMS CREATE ELEMENT TIMTST.COM 

~Remark: Command procedure for tests 
ZCMS-S-CREATED:s element TIMTST.COM created 


Figure 2-1 shows the effects of each action in the building procedure. When Sue and Glenn 
put their files into the library, they used the CMS CREATE ELEMENT command with 


their own file names. 
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Figure 2-1: Building a CMS Library 


2-4 Building a CMS Library 


When determining which files should be in a library, remember that CMS elements must 
be ASCII files. The ASCTI files must have been created or modified by a text editor such as 
EDT. If you are in doubt about a file’s suitability as a CMS library element, check the file 
characteristics in your own directory with the following command. 


$# DIRECTORY /FULL filename,.tyer 
A file must be sequential and cannot have the characteristics of a binary file. If these con- 


ditions are not met, CMS cannot handle the file. See the VAX DEC/CMS Reference Manual 
for more information about file characteristics. 


Once you create elements in a library, you can impose a structure on your library by creat- 
ing groups of elements. A group consists of one or more elements that CMS manipulates as 
a unit. See Chapter 6 for more information about groups. 
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Chapter 3 


Accessing Files in a CMS Library 


This chapter describes the CMS commands that you use to access files in a CMS library. 
These commands perform the following functions: 


The CMS SET LIBRARY command gives you access to a particular library. 


The CMS RESERVE command copies a generation of an element file to your current 
default directory. You perform all program modifications and testing in your own 
directory with an editor, compiler, and utility. CMS records the reservation transac- 
tion and marks the element as reserved. 


The CMS UNRESERVE command cancels your reservation and leaves the element 
copy in your directory. CMS marks the library element as available for other reserva- 
tions and records the transaction. Since there are no modifications to the library ele- 
ment, CMS does not update the library element. 


The CMS REPLACE command copies the latest version of the element file from your 
current default directory to the CMS library, creating a new generation of the ele- 
ment. CMS deletes the element file from your directory, allows you to enter a remark 
to document the changes, records the transaction, and concludes your reservation. 








The CMS FETCH command copies an element into your current default directory. 
The copy is treated as a read-only version for information, not for modification. An 
element is not reserved when it is fetched, therefore fetched copies cannot be returned 
to the library with the CMS REPLACE command. 


‘he sections that follow illustrate how each command can be used in various project | 
ituations. 


a1 


Getting Started — CMS SET LIBRARY 


efore you can use CMS commands on an existing CMS library, you must use the CMS 
ET LIBRARY command to establish access to that library. To set your library, type CMS 
ET LIBRARY followed by the CMS library directory name. Each user must supply the 
ame of the library directory when using the command: 


CMS SET LIBRARY directory 


fter Rick built the CMS library, he told Glenn and Sue the library directory name, 
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{[PROJECT.ADSLIB]. Glenn included the SET LIBRARY command in his LOGIN.COM 
file so that each time he logged on to the system, he automatically had access to the library 
elements. He entered the following command in his LOGIN.COM file: ° 


$ CMS SET LIBRARY CPROJECT.ADSLIBI 


Rick put the same command in his own LOGIN.COM file, but Sue decided to issue the CMS 
SET LIBRARY command each time she wanted to work on the data sampler. 


After you have established access to a library, you can display the name of your CMS 
library directory by using the CMS SHOW LIBRARY command: 


$ CMS SHOW LIBRARY 


When you have access to an existing CMS library, CMS responds with the name of your 
CMS library directory. If you do not have access to a library, CMS returns the following 
message: 


ZCMS-E-NOREF> error referencing CMS$LIB: 


3.2 Reserving a Library Element — CMS RESERVE 


Most of your dealings with the CMS library for your project consist of reserving library 
elements for work and replacing modified elements back into the library. If you have estab- 
lished access to a library (see Section 3.1) you can select an element and reserve it. 


Use the CMS RESERVE command to reserve a library element. CMS always expects you 
to enter a remark when you reserve an element. The remark that you enter should explain 
why you are reserving the element. CMS then accepts your CMS RESERVE command and 
copies the element into your current default directory. CMS marks the element with your 
reservation and records the transaction in the library transaction history. While you have 
an element reserved, anyone reserving any generation of the same element receives a 
CMS message informing them that you have the element reserved. 


At one point during the data sampling project, Sue Kelley reserved the element 
SYNCHRON.BAS to debug a problem about lost data from one of the input channels. The 
reservation transaction follows: 

$ CMS RESERVE SYNCHRON.BAS 


_~Remark: losing sample from one data line 
ZCMS-S-RESERVED» generation 2 of element SYNCHRON.BAS reserved 


CMS places a copy of the element in Sue’s current default directory and displays a mes- 
sage, indicating that generation 2 of element SY NCHRON.BAS is reserved. 


By default, CMS retrieved the most recent generation of the element SYNCHRON.BAS 
(generation 2). If Sue wanted to reserve an earlier generation to see if the same problem 
existed, she could have specified the earlier generation with the /GENERATION qualifier. 
That reservation transaction would have been as follows: 
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¢ CMS RESERVE SYNCHRON.BAS /GENERATIONA-} 
~Remark: Checking data line sampling 
ZCMS-S-RESERVED, generation 1 of element SYNCHRON.BAS recerved 


Sue would have received a copv of the first generation of the element in her current default 
directory. 


A remark can be entered in quotation marks in the same line with any CMS command. Sue 
could have typed: 


$ CMS RESERVE SYNCHRON.BAS "losing sample from one data line" 


If any generation of an element is already reserved by another person, CMS responds to 
your request by issuing a message about the reservation already in effect. You then have 
the option to proceed with your reservation or to quit. Usually two people choose not to 
work on the same element concurrently. However, should the need arise, CMS provides the 
mechanism to handle concurrent development. See Chapter 5 for information about con- 
current reservations. 


3.3 Canceling a CMS Reservation — CMS UNRESERVE 


When you reserve a library element with the CMS RESERVE command and then decide 
not to modify that element, you can cancel your reservation with the CMS UNRESERVE 
command. CMS accepts your UNRESERVE command and the remark you enter with it, 
marks the element as available, and records the cancellation in the library history. CMS 
does not update the element generation number when you cancel a reservation. 


The CMS UNRESERVE command is useful when you accidentally reserve the wrong ele- 
ment, or when you want to make an unmodified element available for another user, or 
when you do not want your modifications to become part of an element. When you use the 
CMS UNRESERVE command, the element in the library is not modified; it remains the 
same as it was when you reserved it. 


For instance, Glenn Lewis reserved a project element to diagnose a problem. A quick view 
of the file showed him that he had selected an element that was not related to the problem. 
He used the CMS UNRESERVE command to cancel his reservation for that element. 


$ CMS UNRESERVE SYNCHRON.BAS 
_Remark: pr G4 not arplicable - wrong file 
ZCMS-S-UNRESERVED, element SYNCHRON.BAS unreserved 


CMS canceled Glenn’s reservation, leaving SYNCHRON.BAS available for other users. 
CMS left the copies in Glenn’s directory and recorded the transaction. 


3.4 Replacing a Modified Element in the Library 


After modifying a reserved slsment: you put the modified siseieat back in the project 
library with the CMS REPLACE command. This command brings the library up to date on 
element modifications and documents them. 
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Use the CMS REPLACE command when you complete work on an element. The CMS 
REPLACE command copies the latest version of the element file from your current default 
directory into the project library. CMS then deletes all copies of that element from your 
directory, assigns a new CMS generation number to the stored element generation, and 
ends your reservation of that element. CMS also records the transaction. 


For example, Rick reserved the current generation (generation 3) of the data sampler’s 
functional specification to correct a typographical error. When he finished correcting that 
element, he replaced it. 


$ CMS RESERVE SPEC.RNO 
-Remark: Misspelling in Reliability section 
ZCMS-S-RESERYVED>,» generation 3 of element SPEC.RNO reserved 


+ 
+ 


+ 


$ CMS REPLACE SPEC.RNO 
_Remark: Reliability section typo fixed 
%ZCMS-S-GENCREATED>s> generation 4 of element SPEC.RNO created 


CMS ended Rick’s reservation of SPEC.RNO, deleted all copies from Rick’s current default 
directory, and recorded the transaction. 


You can use the CMS REPLACE command with its (RESERVE qualifier when you wish to 
update the library while retaining the element for additional modifications. This form of 
the command continues your reservation of the element. The /RESERVE qualifier also 
prevents CMS from deleting any copies of the element from your directory. CMS assigns a 
new generation number to.the stored element generation and records the transaction 
along with your remark. 


In the sample project, Glenn had three separate problem reports to check against a single 
element. As he solved each problem, he used the CMS REPLACE command with the 
/RESERVE qualifier to document his modifications. The first two transactions follow: 


$ CMS REPLACE SAMPLE.BAS /RESERVE 

~Remark: pr 4 - doc. error fixed - doing 5 next 
%CMS-I-GENCREATED: generation 2 of element SAMPLE.BAS created 
~CMS-S-RESERVED:+s generation 2 of element SAMPLE.BAS reserved 


+ 
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$ CMS REPLACE SAMPLE.BAS /RESERVE 
Remark: pr 5 - double precision added 
ZCMS-S-GENCREATED:? generation 3 of element SAMPLE.BAS created and reserved 


CMS updated the library with two new generations of the element, but Glenn stil] had his 
copy for the next modification, and the element was still reserved for him. Each of the gen- 
erations was documented with Glenn’s comments in the library history. 
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You should replace a modified element whenever you reach a isgical stopping point in 
development. This gives you a record of the specific reason for the element modification. 
For example, when you modify a reserved element by adding a single routine and have no 
further work to do on that element, use the CMS REPLACE command to document that 
addition and return the element to the library. When you want to make several different 
modifications to a reserved element, use the CMS REPLACE /RESERVE command after 
all but the last modification. This allows you to document each modification but retain the 
element for further work. 


If you replace an element that was concurrently reserved and then replaced by another 
user, you must create an alternate development path. (Refer to Chapter 5 for information 
on alternate development paths.) 


3.5 Getting a Read-only Copy 


The CMS FETCH command copies an element file into your current default directory. 
Unlike the CMS RESERVE command, CMS FETCH does not mark an element reserved, 
and CMS does not allow you to replace a fetched copy in the library. You can fetch a copy of 
an element whether the element is reserved or not. Use the /GENERATION qualifier to 
fetch an earlier generation of the element. 


Whenever Rick needed to check his modifications to the data sampling software he used 
the CMS FETCH command to retrieve a copy of the testing command file, TIMTST.COM. 
For example: 

$ CMS FETCH TIMTST.COM 


~Remark:s Testing storage tlocks 
ZCMS-S-FETCHED: Element TIMTST.COM:s: generation 2 fetched 


CMS delivered a copy of the file to Rick’s directory, and he used it to test his modifications. 
When he finished testing his modifications, he simply deleted TIMTST.COM from his 
directory. This transaction did not affect the library copy of the file. 


A situation may arise in which you need to fetch an element that you have previously 
reserved. If, for example, you wish to abandon a series of edits and start over, fetch the 
element generation that you have previously reserved. If your current default directory 
already contains a copy of the file you are fetching, CMS notifies you and continues the 
transaction. In this case, CMS assigns the next higher file version number to the new file 
and displays the following messages: 


ZCMS-I-FILEXISTS+ file already exists, DRAI:CTESTSITEST.FORS2 created 
ZCMS-S-FETCHED>» generation 3 of element TEST.FOR fetched 


When you issue the CMS REPLACE command, CMS always moves the highest-numbered 
version of an element file from your current default directory to the library. Thus, if you 
most recently worked on the fetched version, the changes that correspond to the fetched 
version will be stored in the library. 
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Chapter 4 


CMS Show Commands 


As you begin to work with an existing CMS library, you might need additional information 
about it. The CMS SHOW commands provide information about the library structure, his- 
tory, and current status. This chapter contains information about several of the CMS 
SHOW commands. The following list indicates the kind of information that you can get by 
using each of these commands. 


e What files are in the library? -CMS SHOW ELEMENT (Section 4.1) 
e What files are being worked on? - CMS SHOW RESERVATIONS (Section 4.2) 
e What transactions have occurred? -CMS SHOW HISTORY (Section 4.3) 
-e What is generation n of element X?—- CMS SHOW GENERATION (Section 4.4) 
e How did element X evolve?— CMS SHOW GENERATION/ANCESTORS (Section 4.5) 


e What evolved from element X? - CMS SHOW GENERATION/DESCENDANTS 
(Section 4.6) . 


4.1 What Files Are in The Library? - CMS SHOW ELEMENT 


The CMS SHOW ELEMENT command displays an alphabetical list of the elements that 
are in your library. For instance, in the sample project Rick used the CMS SHOW 
ELEMENT command to see which elements were in the project library. CMS reported six 
2lements in the library. 


6 CMS SHOW ELEMENT 
=lements in DEC/CMS Library DRA: CPROJECT.ADSLIB]I 
JOCONVERT.BAS “analogs to digital conversion routines” 


“<RRMSG. TXT "initial load" 

SAMPLE.BAS "Sampling module” 

3PEC.RNO "ADS functional specification" 
SYNCHRON.BAS "Synchronization routines" 
FIMTST.COM “Command procedure for tests" 


4-1 


4.2 What Files are Being Worked On? — CMS SHOW RESERVATIONS 


The CMS SHOW RESERVATIONS command lists those reservations currently in effect. 
In the sample project, Rick used this command to see which elements were being worked 
on: 


¢ CMS SHOW RESERVATIONS 
CMS reported which elements were reserved, who reserved the element, the generation 


that was reserved, when, and why. Rick used this command to determine whether or not 
any files from his default directory should be returned to the library. 


Reservations in DEC/CMS Library DRA3S:[CPROJECT.ADSLIB] 


SAMPLE.BAS 

LEWIS 1 3O0-JUN-1984 11:19:29 “add code for more data lines" 
SYNCHRON.BAS 

KELLEY 3 18-JUN-1984 09:42:03 “integrate a/d conversion” 


4.3 What Transactions Have Occurred? — CMS SHOW HISTORY 


Whenever you create, retrieve, or replace a library element, CMS stores information about 
the transaction in its chronological history file. Various CMS SHOW commands display 
historical information about the library. For example, the CMS SHOW HISTORY com- 
mand allows you to review a chronological list of all library transactions. Early in the sam- 
ple project, Sue used this command to request a record of library transactions: 


$ CMS SHOW HISTORY 


CMS reported the following: 
History of DEC/CMS Library DRA3:C{PROJECT.ADSLIB] 


1-MAY-1984 14:22:16 SANCHEZ CREATE LIBRARY DRAG: CPROJECT.ADSLIBJ] "a/d data 
sampling library" 

1-MAY-1984 14:26:47 SANCHEZ CREATE ELEMENT SPEC.RNO "ADS functional 
specification” 

i-JUN-1984 12:09:02 SANCHEZ CREATE ELEMENT ADCONYVERT.BAS “analog to digital 
conversion routines" 

1-JUN-1984 12:25:41 SANCHEZ CREATE ELEMENT SAMPLE.BAS "Sampling module" 

1-JUN-1984 12:29:24 SANCHEZ CREATE ELEMENT SYNCHRON.BAS "Synchronization 
routines" 

1-JUN-1984 14:01:36 SANCHEZ CREATE ELEMENT TIMTST.COM “Command procedure for 
tests" 

S-JUN-1984 14:47:40 KELLEY RESERVE SYNCHRON.BAS(1) "losing sample from one 
data line" 


Note that CMS does not record transactions that do not alter the library. (These commands 
include CMS ANNOTATE, CMS DIFFERENCES, CMS SET LIBRARY, and CMS SHOW 
commands. CMS logs fetch transactions only if you supply a remark.) 
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Once your librarv has a large number of transactions, you can limit the CMS SHOW 
HISTORY display with the /SINCE=date qualifier. If Sue had used CMS SHOW 
HISTORY /SINCE = 15-MAY-1984, CMS would have reported only the transactions since 
that date. 


The CMS SHOW HISTORY command can be used with the qualifier /UNUSUAL to report 
any abnormal library transactions that occurred, for example, two reservations in effect 
for the same element at the same time. 


4.4 What Is Generation n of Element X? — CMS SHOW GENERATION 


When you need information about a specific generation of an element, use the CMS SHOW 
GENERATION command to list the transaction that created the generation. When you 
include a generation number, it must be specified with the /GENERATION quailifier. If you 
omit a generation number, CMS assumes the most recent generation. 

Rick investigated the creation of generation 3 with the following command: 


$ CMS SHOW GENERATION SYNCHRON.BAS /GENERATION=3 


CMS replied: 
. SYNCHRON.BAS 3 26-JUN-1984 09:44:12 KELLEY “a/d conversion integrated" 


4.5 How Did Element X Evolve? - CMS SHOW GENERATION /ANCESTORS 


The CMS SHOW GENERATION /ANCESTORS command lists the transactions that cre- 
ated each prior generation of the element. CMS produces a list in reverse chronological 
order with one line about each generation. Each line includes the element name, genera- 
tion number, user name, date, time, and remark of the transaction that created the 
generation. 


You can limit the listing by using the /GENERATION qualifier to specify a generation 
number; in this case, the generation listing begins with the specified generation. If you 
omit a generation number, CMS provides a complete ancestor list from the most recent 
library version back to generation 1. 


During the data sampler project, Glenn Lewis began medifications to the element 
SYNCHRON.BAS sometime after Rick and Sue had both worked on it. To review the his- 
tory of the element, he used the CMS SHOW GENERATION /ANCESTORS command as 
follows: 


$ CMS SHOW GENERATION /ANCESTORS SYNCHRON.BAS 
CMS listed the following transactions: 
SYNCHRON.BAS | 


3 26-JUN-1984 09:44:12 KELLEY "“a/d conversion integrated” 
zZ 10-JUN-1984 13:10:12 KELLEY "last data line included" 
1 1-JUN-1984 12.29.24 SANCHEZ “Srnchronization routines" 
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CMS ShOW GENERATION /ANCESTORS reported that the current version of 
SYNCHRON.BAS is generation 3, which was replaced by Sue Kelley at 9:44 A.M. on June 
26 after she integrated the conversion code. The previous generation (also created by Sue) 
involved modifications to correct errors. Rick Sanchez placed the original element in the 
library on June 1. 


4.6 What Evolved from Program X? — CMS SHOW GENERATION 
/DESCENDANTS 


To get a report of all subsequent generations of an element, use the CMS SHOW 
GENERATION /DESCENDANTS command. It allows you to specify a generation number 
with the ‘(GENERATION qualifier; generation 1 is the default generation. As in the dis- 
play of ancestors, CMS SHOW GENERATION /DESCENDANTS lists the generations in 
reverse chronological order. 


For example, Rick knew that generation 2 had been debugged, so he requested only its 
descendants: 


$ CMS SHOW GENERATION /DESCENDANTS SYNCHRON.BAS /GENERATION=2 


CMS would list the following transactions: 


SYNCHRON.BAS 
3 26-JUN-1984 09:44:12 KELLEY “a/d conversion integrated" 
2 10-JUN-1984 13:10:12 KELLEY “last data line included” 


The CMS SHOW GENERATION /DESCENDANTS command reported that the problem 
was resolved in generation 2 and that generation 3 includes new conversion code. This 
command is also useful if you do not know if any variant lines of descent have been created 
(see Chapter 5). 
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Chapter 5 


The Evolving CMS Library 


Chapters 1, 2, and 3 describe how to use CMS commands to store and update a fileina CMS 
library. The examples in these chapters show how to use CMS to build the main develop- 
ment path of an element, called the main line of descent. 


Some circumstances require alternate development paths for project programs: for exam- 
ple, a change in scope of an existing program, trial development of a slightly different 
internal program structure, or the discovery of an error in an earlier generation of an 
2xisting program. To handle these circumstances, CMS allows you to establish a path that 
is a variant of the main line of development — a branching in the evolution of the element. 
OMS maintains a complete history in support of alternate development paths. 


lhis chapter describes the use of the (VARIANT qualifier on the CMS REPLACE com- 
nand for creating alternate development paths. It describes the /MERGE qualifier for the 
MS RESERVE and CMS FETCH commands. The /MERGE qualifier allows you to com- 
yine two paths of development. This chapter also describes concurrent reservations. Pro- 
7ram evolution is illustrated in diagrams that show successive states of a library. 


3.1 Alternate Development Paths 


\n alternate development path in CMS is known as a variant line of descent. You establish 
| variant line by using the /VARIANT =x qualifier on the CMS REPLACE command. This 
reates a variant generation that CMS can distinguish from the main line of descent. The 


sarameter x, called the variant letter, is any single alphabetic character. The format of the 
ommand is as follows: 


- CMS REPLACE element-name /VARIANT=x 


»MS copies the element from your default directory into the library and labels the variant 
eneration by appending the variant letter and the numeral 1 to the generation number. 
‘or example, if you had reserved generation 7 of an element named TEST1.FOR, you could 
reate a variant as follows: 


CMS REPLACE TEST1.FOR /VARIANT=A 
Remark: Routine added for multi-user system 
CMS-S-GENCREATED:+ generation 7A!i of element TEST1I.FOR created 
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The number after the letter A identifies successive generations on that variant branch. If 
you reserve and replace generation 7A1 of TEST1.FOR, generation 7A2 will be created. 
For added meaning, you can choose a variant letter that indicates the purpose of the vari- 
ant line — “A” for alternate, “B” for bug fixes, “E” to indicate enhancements, and so forth. 
Each variant can have variants of its own using the same /VARIANT method; for example, 
a variant to 7A1 could be replaced with /VARIANT = E to become 7A1E1. 


During the data sampler project, Glenn knew that the program SAMPLE.BAS would have 
to be tested in two separate environments, and that some differences would exist in the 
code for each environment. He decided to establish a variant to the current main line for 
the second system. Glenn reserved the most recent main line element and then replaced it 
as a variant, starting a variant line of development. Figure 5-1 shows the main line devel- 
opment for SAMPLE.BAS prior to the variant path. Figure 5-2 shows the parallel line of 
development after the program was replaced as a variant. Glenn’s procedures to establish 
the variant line of descent were as follows: 


$ CMS RESERVE SAMPLE.BAS 

-Remark: handle different input for second system 
ZCMS-S-RESERVED> element SAMPLE.BAS» generation 3 reserved 
(modification and test) 

$ CMS REPLACE SAMPLE.BAS /VARIANT=A 

-Remark: Modified for second system 

ZCMS-S-GENCREATED>» generation 3A1 of element SAMPLE.BAS created 


Now Glenn could test the variant in a different environment, keeping the main line gener- 
ation for his first target system. 
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Figure 5-1: Main Line Evolution 
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Figure 5-2: Variant Line Evolution 
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5.2 Merging Alternate Development Paths . 


At some point in development, you may want to merge the changes made to an element in 
a variant line back into the main line of descent. When you reserve an element from the 
library, you can merge any two generations of the element that are not on the same line of 
descent. Use the /MERGE = y qualifier on the CMS RESERVE command; y is the genera- 
tion that is merged into the reserved generation. 


If you are merging a generation on the main line into a variant generation, you reserve the 
variant, and specify the main line generation number as the value for the /MERGE qualli- 
fier. (The (MERGE = y qualifier can also be used with the FETCH command if you wish to 
only see merge results, without updating the library.) 


The /MERGE qualifier directs CMS to identify the common ancestor, the most recent gen- 
eration that is common to both lines of descent. Internally, the subsequent changes in both 
lines of descent are integrated with the common ancestor. 


When you merge two generations of an element, CMS creates a file in your current default 
directory. This file contains the results of the merge transaction. Because merging is only a 
mechanical process, you must always check to be sure that the result is what you intend. If 
there are conflicting modifications, CMS flags these lines in the file. As you are checking 
the program for accuracy, you must resolve these conflicts. 


To continue with the earlier example, Glenn decided after producing two generations of 
SAMPLE.BAS on each development path, that the two paths should be combined. The 
combined generation of SAMPLE.BAS would have code from each development path. 


Glenn used the CMS RESERVE command with its ‘(MERGE qualifier to combine the two 
generations and produce a single main line generation. Figure 5-3 illustrates the combin- 
ing of the two generations into a merged copy in his default directory. Glenn used the fol- 
lowing CMS command to merge the two generations: 


$ CMS RESERVE SAMPLE.BAS /MERGE=3A2 

~Remark: Combining sys2 version into dual-support version 
ZCMS-I-MERGECOUNT: 4 changes successfully merged with no conflicts 
ZCMS-S-RESERVED: generation 5 of element SAMPLE.BAS reserved and merged 
With generation 3AZ2 
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Figure 5-3: Merging Element Generations 


[he CMS RESERVE command with the /MERGE qualifier did the clerical work of combin- 
ng the changes from the two lines of development. CMS reported that four areas of 
‘hanges in generations 5 and 3A2 did not conflict and were incorporated successfully into 
he default directory copy. After compiling and testing the program, Glenn used the CMS 
*EPLACE command to create generation 6 on the main line. 
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5.2.1 Replacing a Merged Copy 


Glenn used the following command to return the merged default directory copy of 
SAMPLE.BAS to the library as generation 6 on the main line: 


$ CMS REPLACE SAMPLE.BAS 
~Remark: 3A2 and S merged for dual-surrort 
YCMS-S-GENCREATED,> generation 6 of element SAMPLE.BAS created 


Figure 5-4 shows the library after the merged version of the element was replaced. 
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Figure 5-4: A Merged Element 


5.2.2 Resolving Merge Conflicts 


When you merge two generations with either the CMS RESERVE command or the CMS 
FETCH command, CMS checks for conflicting changes at the same line of the code. CMS 
notifies you of any conflicts and flags the conflicting lines so that you can resolve the prob- 
lem. Example 5-1 shows a flagged conflict in a source file. 
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~ 


15 OPTION TYPE = EXPLICIT 

au DECLARE STRING DELTA_TIME 

EHEKEKHEHHHEHHREEKSE Conflict i HEE KEKHEEEKEKEEKEHEEHREREKRKEKRHHEHKHKEHRHREEEHRR ER HEHEHE 
DECLARE STRING ASC_TIME 

ERKKEKKE HEHEHE HERE KEE REE HHEKRKEHEE EKER KERR HERE HRK KEKE RHR HEEKRHHHRRKRHER EE HED: 
MAP (STRING_LEN) STRING ASC_TIME = 80 

HHHHHEHEE End of Conflict 1 HEHEHE KEHEHEHHAHRHEHRHKKEHRHRHEHEHHKEHHHHHRHKRHHHHEHH HHH ERG 
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DECLARE LONG RETCODE 
OW DIM LONG BINARY_DELTA(1) 


DIM LONG NOW(1) 
DIM LONG BINARY_CVT_TIME(1) 


Example 5-1: Merge Conflicts Flagged 


Each conflict is flagged with the word “Conflict” and a sequential conflict number in a line 
of asterisks. Following the asterisks, CMS displays the conflicting segments of text. 


When you resolve the conflicts, use a text editor (for example, EDT) to delete the unwanted 
lines and the asterisks from the file, and return the copy to the library with the CMS 
REPLACE command. 


5.3 Working Simultaneously on the Same Element 


Situations can arise in which two people must work on the same element at the same time. 
For example, one person has already reserved an element when a second person enters a 
CMS RESERVE command for the same element. CMS informs the second person that the 
element is reserved. At this point, the transaction can be terminated, or, the second 
reserver can disregard the CMS message, reserve the element, and modify one of its gener- 
ations. When the first reserver replaces the element, CMS reports that a concurrent reser- 
vation was made and tells who the second reserver was. Even if the second reserver has 
already replaced the element, CMS reports the replacement transaction to the first person. 
For example, if you reserve element TEST.BAS for modification after another person has 
reserved it, you cause a concurrent reservation for element TEST.BAS. CMS always noti- 
fies you if an element is already reserved. 


If you cannot avoid a concurrent reservation, be aware that some additional effort is 
involved when replacing concurrently-reserved elements. The following sections show the 
procedures for reserving an already-reserved element and for replacing such an element 
into the library. : 
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5.3.1 Reserving an Element That Is Already Reserved 


If the library element you wish to modify is already reserved by another person, CMS 
accepts your CMS RESERVE command and the remark you enter with it. Then CMS 
reports that the element is currently reserved and by whom. You may not reserve an ele- 
ment you have already reserved. If you use the CMS RESERVE command on an element 
you have already reserved, CMS reminds you with the following message. 


ZCMS-E-NORESERVATION: error reserving element TEST1I.FOR 
-~-CMS-E-RESERVEDBYYOQU, element TEST1.FOR is already reserved by you 


Once CMS tells you about a previous reservation, it still gives you the option to reserve the 
element at that time. If you choose to proceed, CMS delivers a copy of the element to your 
default directory, marks the element as concurrently reserved by you, and notes the reser- 
vation transaction in the library history. Because concurrent reservations are not normal 
for the library, CMS notes the concurrent reservation as an unusual condition. Unusual 
conditions are displayed with the CMS SHOW HISTORY /UNUSUAL command. 


In the sample project, when Glenn Lewis reserved the element SAMPLE.BAS, CMS 
reported that Sue was updating the element by adding a new search routine. Glenn chose 
not to work on the element at the same time. That reservation interaction was as follows: 


$ CMS RESERVE SAMPLE.BAS 
-~Remark: Change conversion input 
ZCMS-I-RESBY, Currently Reserved by 
KELLEY Generation 7? 31-SEP-1984 08:15:47 “extending conversion" 
Proceed? [Y/N] (N}: no 


Glenn decided not to reserve SAMPLE.BAS at the same time Sue was updating it. He 
waited until she replaced the modified element into the project library before making his 
modifications. 


Another time Glenn had no choice but to reserve an element concurrently. Rick had 
reserved the element SYNCHRON.BAS for modifications, and he was out of the office 
when Glenn needed to change the element to diagnose a problem at a test site. Glenn 
reserved the element as follows: 


$ CMS RESERVE SYNCHRON.BAS 
-Remark: Remote site down - 7th Phone call! 
ZCMS-I-RESBY, Currently Reserved by 
Sanchez Generation 4@ 10-SEP-1982 10:36:24 "Changing FLDEXP" 
Proceed? CY/NJ] (Nd): yes 
ZCMS-S-RESERVED; Element SYNCHRON.BAS» generation 4 reserved 


Once he had reserved SYNCHRON.BAS, Glenn made the modifications to solve the test 
site’s problem. He then replaced SY NCHRON.BAS, creating generation 5. 


5-8 The Evolving CMS Library 


3.3.2 Replacing an Element That Has Already Been Replaced 


When two users modify the same element at the same time, the first user can replace the 
modified generation with the normal CMS REPLACE command to produce the next gener- 
ation. However, the second user must replace the modifications as a variant generation. 
One or the other can then choose to merge that variant back into the main line so that both 
sets of program modifications appear in one generation. 


When Rick returned, he used the CMSSHOW RESERVATIONS command to see what was 
out of the library at the moment. CMS listed his reservation of SYNCHRON.BAS and 
showed that Glenn had reserved and replaced the element while Rick was away. 


$ CMS SHOW RESERVATIONS 


¢ 
+ 


+ 


SYNCHRON.BAS 


SANCHEZ 4 10-SEP-1982 10:36:24 “changing FLDEXP" 
Concurrent Replacements 
LEWIS ba) 14-SEP-1982 15:04:52 “Added switch test" 


¢ 
+ 


+ 


‘Now Rick had to resolve the differences between generation 4 of the element, which was 
reserved and in his directory, and generation 5, which Glenn had replaced in the library. 
His choices were: | 7 


e To cancel his reservation with the CMS UNRESERVE command. This would be the 
simplest solution if he had not done any work on the element. Rick would then reserve 
the generation Glenn had replaced. 


e To replace the modified element in the library as a variant generation of the element 
using the CMS REPLACE /VARIANT command, and then make another reservation 
with the /MERGE qualifier. CMS would combine the changes, identifying any con- 
flicts between the two generations. Rick and Glenn could resolve any conflicts and 
replace the merged element as generation 6. 


Since Rick had already modified the program, he chose the second option as the most effec- 
tive, and entered the following CMS commands: 


The Evolving CMS Library 5-9 


$@ CMS REPLACE SYNCHRON. Bas . JARIANT=A. 

_Remark: Fixed but w/o change for reméte site 

%CMS-S-GENCREATED> generation 4Al of element SYNCHRON.BAS created 
$$ CMS RESERVE SYNCHRON.EAS /MERGE=4A1 

-Remark: Merging 5S (remote fix) and GA (table fix) 
ZCMS-S-MERGECOUNT;, 3 changes successfully merged with no conflicts 
ZCMS-S-RESERVED>» generation 5 of element SYNCHRON.BAS reserved and merged 
With generation 4A! 

(read and test) 

$ CMS REPLACE SYNCHRON.BAS 

~Remark: Replacing merged element - no changes needed 
ZCMS-S-GENCREATED, generation 6 of element SYNCHRON.BAS created 


There were no conflicting lines in the merged generations. Had any of the modifications 
been made to the same line in the program, CMS would have noted these as conflicts. 
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Chapter 6 


Project Organization with CMS 


Earlier chapters in this manual describe how CMS can be used for storing project files and 
for tracking the changes to these files during development. The commands that perform 
these functions can be used by any one library user without a great deal of interaction with 
other team members. Yet CMS is a project tool, and a project usually involves a number of 
people. This chapter describes CMS as an organization and communication tool for any 
number of people on a project. The commands described are basic commands; full com- 
mand capabilities are described in the VAX DEC/CMS Reference Manual. 


6.1 The Early CMS Library 


Figure 6-1 shows the early data sampler project library. Although the various elements 
have been worked on by more than one project member, each element has evolved indepen- 
dently. After the first generation of each element was placed in the library, the program- 
mers modified and. tested the elements, thereby creating new generations each time they 
returned the elements to the library. 


CMS LIBRARY 


SAMPLE BAS [SYNCHRON BAS J ADCONVERT.BAS] DISPLAY BAS TIMETST COM SPEC.RNO 





ZK-1755-84 


Figure 6-1: An Early CMS Library 


For example, note that the element SAMPLE.BAS had evolved to its seventh generation 
when this “snapshot” of the library was taken; yet by the same date the functional specifi- 
cation, SPEC.RNO, had been modified only once. The rest of this chapter builds on this 
basic diagram to demonstrate how CMS aids interaction among project members. For clar- 
ity, only six of the project library elements are shown in the diagrams. 
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6.2 Using CMS Groups 


CMS uses the element as the basic structural unit in a library. However, you can combine 
one or more elements into a group that you can manipulate as a unit. Also, you can use 
groups to reflect the general structure of the software project. The following sections 
describe how to build and manipulate CMS groups. 


= 


6.2.1 Building a CMS Group 


To build a group, you create an empty group with the CMS CREATE GROUP command. 
Then you use CMS INSERT ELEMENT commands to associate elements with that group 
name. 


The project team established a group tc contain elements that handled data. They created 
the group and then inserted elements into that group with the following commands: 


$ CMS CREATE GROUP DATA_ROUTINES 

~Remark: routines for input & conversion 

ZCMS-S-CREATED» group DATA_ROUTINES created 

$ CMS INSERT ELEMENT SAMPLE.BAS DATA_ROUTINES 

—-Remark: input sampling routines 

ZCMS-S-INSERTED>s element SAMPLE.BAS inserted into grourp DATA_ROUTINES 

.$ CMS INSERT ELEMENT ADCONVERT.BAS DATA_ROUTINES 

-Remark: analog-to-digital conversion 

ZCMS-S-INSERTED+ element ADCONVERT.BAS inserted into group DATA_ROUTINES 


By using the CMS INSERT ELEMENT command, you can insert individual elements into 
a group. You can also use the CMS INSERT GROUP command to associate a group of ele- 
ments with another group. Because this is a bookkeeping function, the insertion of ele- 
ments (or groups) into a specific group is only a logical connection. No physical merging of 
elements occurs, so you can access individual elements as usual. See the VAX DEC/CMS 
Reference Manual for more information about using these commands. 


6.2.2 Using the Group Designation 


Once you define a group, CMS allows you to access all the elements in the group by specify- 
ing the group name. For example, Rick wanted to check the latest generations of each of 
the modules that process the input data. He used the following command to fetch all of the 
- appropriate elements: 


$ CMS FETCH DATA_ROUTINES “checking signal storage” 


CMS retrieved the latest main line generation of each of the elements belonging to the 
group DATA_ROUTINES. 


6.2.3 Removing Elements from Groups 


The CMS REMOVE ELEMENT command allows you to eliminate an element from a 
group. This command only removes the association between an element and a group; it 
does not alter or delete the element. 
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The project team had created a group named DOCUMENTATION; for some time, this 
group contained only the element SPEC.RNO, the functional specification for the 
software. As the project progressed, they hired a writer, Paul Abbott. Paul created several 
elements in the library for the user’s manual. When the documentation was ready for 
review, he decided to use the group DOCUMENTATION. To keep the functional specifica- 
tion separate from the user documentation, he removed SPEC.RNO with the following 
command: 

$ CMS REMOVE ELEMENT SPEC.RNO DOCUMENTATION 


_-Remark: user’s manual ready for first review 
ZCMS-S-REMOVED, element SPEC.RNO removed from grourp DOCUMENTATION 


6.2.4 Displaying the Group Structure of a CMS Library 


To find out what groups are defined in your library, use the CMS SHOW GROUP com- 
mand. CMS lists the group names in alphabetical order with the remark that was entered 
when the group was created. To obtain a list of all elements in a specific group, use the CMS 
SHOW GROUP command with the /CONTENTS qualifier. For example, Rick wanted to 
check the contents of the group named DATA_ROUTINES: 


@ CMS SHOW GROUP/CONTENTS DATA_ROUTINES 
Groups in DEC/CMS Library DRA3:CPROJECT.ADSLIB) 


DATA_ROUTINES “routines for input & conversion" 
ADCONVERT.BAS 
SAMPLE.BAS 


6.3 Using CMS Classes 


CMS allows you to define sets of element generations, called classes. CMS keeps track of 
which element generations you assign to a specific class. You can use classes to represent 
milestones for any or all phases of a project. 


The purpose of a class is determined by the methodology used by project members. For 
example, you can establish classes that represent different stages of development for each 
element generation. Each generation represents a cycle that includes several steps: 
reserving the element, adding or changing code, testing, and then replacing the element. 
You can establish classes for different stages; one for implementation, another for testing, 
and a third class for the generations that have completed the first two stages. As each mod- 
ule progresses through each stage, you assign.it to the appropriate class; thus, you can 
easily determine your progress by displaying the contents of the different classes. | 


You can also use classes for system integration. When all the modules reach a working 
stage in development, you integrate the modules into the first working version or “base 
level” of the product for testing. Each module that is used in the base level corresponds to 
an element generation in a CMS library. You can create a class that contains each element 
generation used in the base level. 
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Different base levels represent milestones in the development of a project. For example. 
test versions, internal release versions, and external release versions might be significant 
milestones. A project can also evolve through additional releases with enhancements and 
corrections. These stages vary from project to project, but the life of a project is essentially 
the same for a payroll application program as it is for a compiler project — from design and 
development to test and release, then to maintenance and enhancement. You can establish 
one or more classes to reflect each of the different stages of a project. 


6.3.1 Building a CMS Class 


To build a class, you create an empty class with the CMS CREATE CLASS command. Then 
you use CMS INSERT GENERATION commands to place specific element generations in 
that class. (CMS allows only one generation of an element per class.) The /GENERATION 
qualifier of the CMS INSERT GENERATION command specifies the generation to be 
inserted. When you omit the qualifier, CMS places the most recent main line generation in 
the class. 


On the data sampler project, the team created a class called BASELEVELI and assigned 
specific generations of the library elements to that class. Rick did this with the following 
commands: 


-$ CMS CREATE CLASS BASELEVEL1 

~Remark: Specifying all gens for first base level 

ZCMS-S-CREATED: class BASELEVEL1 created 

$ CMS INSERT SAMPLE.BAS /GENERATION=6 BASELEVEL!I 

~Remark: Checked and OKd by SK 

ZCMS-S-GENINSERTED> generation 6 of element SAMPLE.BAS inserted into class 
BASELEVEL1 

$ CMS INSERT SYNCHRON.BAS /GENERATION=4 BASELEVELI 

—-Remark: Checked and OKd ty RS 

ZCMS-S-GENINSERTED: generation 4 of element SYNCHRON.BAS inserted into class 
BASELEVEL1 

$ CMS INSERT ADCONYVERT.BAS BASELEVELi! 

~Remark: Using latest» checked OK this am - GL 

ZCMS-S-GENINSERTED+ generation 5 of element ADCONVERT.BAS inserted into class 
BASELEVELI 

$ CMS INSERT DISPLAY.BAS BASELEVEL1 

—~Remark: Terminal display of sampled data 

ZCMS-S-GENINSERTED:+ generation 2 of element DISPLAY.BAS inserted into class 
BASELEVEL1 


Figure 6-2 indicates which element generations were inserted in the class BASELEVEL1. 
The class consists of only those element generations specified by the CMS INSERT 
GENERATION commands. Because this is a bookkeeping function, the insertion of gener- 
ations into a specific class is only a logical connection. No physical merging of elements 
occurs, SO you can access individual generations and elements as usual with other CMS 
commands. 
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Figure 6-2: A CMS Library Showing a Defined Class 
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6.3.2 Using the Class Designation 


Once you define a class, CMS allows you to access any element generation in that class by 
specifying the class name. You do not have to know the specific generation number of the 
element. For example, when a problem in the base level was reported to the project team, 
Rick had to test SAMPLE.BAS. To ensure that the proper generation of the element was 
tested, he used the following command: 


$ CMS RESERVE SAMPLE.BAS /GENERATION=BASELEVEL1 


CMS placed the proper element, generation 6, in the default directory, even though the 
latest generation was 7. 


6.3.3 Displaying the Class Structure of a Library 


To find out what classes are defined in your library, use the CMS SHOW CLASS command. 
CMS lists the class names in alphabetical order with the remark that was entered when 
the class was created. To obtain a list of all generations in a specific class, use the CMS 
SHOW CLASS command with the /CONTENTS qualifier. For example, Rick wanted to 
check the contents of the class the project was using for the first base level: 


$ CMS SHOW CLASS/CONTENTS BASELEVEL1 


-CMS listed all of the elements and their generations inserted in BASELEVEL1 as follows: 
Classes in DEC/CMS Library DRA3:CPROJECT.ADSLIB] 


BASELEVEL1 "Specifving all gens for first base level" 


ADCONVERT.BAS ss) 
DISPLAY.BAS 2 
SAMPLE.8BAS 6 
SYNCHRON.BAS i} 


6.3.4 Assigning Elements to Multiple Classes 


In addition to keeping track of an established class, CMS allows you to designate some or 
all of the element generations in one class as belonging to another class as well. This per- 
mits a base level or release to contain various options to the standard version. 


On the sample project, Rick wanted an alternate version of the first base level for demon- 
stration purposes. He needed to suppress some of the newer features that were not fully 
implemented so the data sampler could work without errors when it was demonstrated. He 
used the following procedure to accomplish this: 


He reserved the conversion element, ADCONVERT.BAS. 
He modified it to ignore the new features. 


He replaced the modified element as a variant of the standard element. 


ee oe ae 


He established a new class called DEMOA to contain the modified synchronization 
element and all of the other elements that made up the base level of the data 
sampler. 
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He used the following CMS commands to create class DEMOA: 


¢ CMS CREATE CLASS DEMOA 

_-Remark: Runnable taselevell version - only for demos 

ZCMS-S-CREATED: class DEMOA created 

$¢ CMS INSERT ADCONVERT.BAS /CGENERATIGN=5D1i DEMOA 

-Remark: Modified BLI1 version for demos 

ZCMS-S-GENINSERTED:; generation SDi of element ADCONVERT.BAS inserted into 

class DEMOA 

@ CMS INSERT SAMPLE.BAS /GENERATION=BASELEVEL1 DEMODA 

~Remark: BLi version OK for demos 

ZCMS-S-GENINSERTED;, generation 6 of element SAMPLE.BAS inserted into class 
DEMDA 

$ CMS INSERT SYNCHRON.BAS /GENERATION=BASELEVEL1 DEMOA 

-~Remark: BL1 version OK for demos 

ZCMS-S-GENINSERTED:+ generation 4 of element SYNCHRGN.BAS inserted in class 
DEMOA 

$ CMS INSERT DISPLAY.BAS /GENERATION=BASELEVEL1 DEMOA 

_-Remark: BLI version OK for demos 

ZCMS-S-GENINSERTED; generation 2 of element DISPLAY.BAS inserted in class 

DEMOA 


Figure 6-3 shows the variant, 5D1, branching from the main line of descent for element 
ADCONVERT.BAS. The two different base levels are indicated. Note that BASELEVELI1 
and DEMOA are identical except for ADCONVERT.BAS, which has a different generation 


in each class. 
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Figure 6-3: Multiple CMS Classes 
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6.3.5 Removing an Element from a Class 


The CMS REMOVE GENERATION command allows you to eliminate an element genera- 
tion from a class. For example, suppose that the first base level was going to be reduced in 


scope, and DISPLAY.BAS dropped from the class BASELEVEL1. The command to accom- 
plish this task would be: 


$ CMS REMOVE GENERATION DISPLAY.BAS BASELEVELI 


CMS would then revise its information about BASELEVELI so that DISPLAY.BAS would 
not be included in the class. All future references to BASELEVEL1 would refer to the class 
without DISPLAY.BAS. 


6.3.6 Defining a Release with CMS 


The process for establishing a release version of library elements is the same as it 1s for 
defining a base level — you create a class and then insert appropriate element generations 
into it. The class name could be the release version number (REL1 or RELEASE2A, for 
instance). CMS still maintains the audit trails back to the beginning of the project so that 
the complete project history is available. 


6.3.7 Supporting a Product Using CMS 


When an error is reported in either a base level or a release version of a product, careful 
tracking is needed to ensure that the appropriate generation is corrected. It is also neces- 
sary to maintain the integrity of that version with proper historical information. CMS 
helps merge the modification into the product code and preserves the integrity of the 
library history. 

The CMS INSERT GENERATION command, when used with the /ALWAYS qualifier, lets 
you correct a class and replace the problem generation with a corrected generation. Any 
existing generation of that element is removed from the class, and the generation specified 
takes its place. 


In the sample project, an error within an element used in the first release required correc- 
tion. The corrected element was needed to replace the incorrect module in the release class. 
Mike corrected the problem in the following way. 


1. He reserved the element generation containing the error. 

2. He modified and tested the element until it was satisfactory. 
3. He replaced the corrected element as a variant. 
4 


He inserted the generation in the class while superseding the previous generation 
of the element. 


These are the commands he used: 
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$ CMS RESERVE DISPLAY.E4S /GENERATION=RELEASE1! 
-~Remark: PR No. 4 - To fix uninitialized variatle 
ZCMS-S-RESERVED» element DISPLAY.BAS:» generation 9 reserved 


(debugy» modification and test) = 

$ CMS REPLACE DISPLAY.BAS /VARIANT=B 

-Remarks: Additional initialization done - R1-PR-4@ fixed 

ZCMS-S-GENCREATED> generation SB! of element DISPLAY.BAS created 

$ CMS INSERT GENERATION DISPLAY.BAS /GENERATION=981 RELEASE1 /ALWAYS 

-Remark:s PR No. 4 - replacement for gen G9 bug in Rel 1 

ZCMS-S-GENINSERTEDs generation 9B1 of element DISPLAY.BAS inserted into 
class RELEASE1 


Part A of Figure 6-4 shows the portion of the library with the class RELEASE 1 in its origi- 
nal form. Part B of Figure 6-4 shows the project library after the error in element 
DISPLAY.BAS had been corrected. The class name RELEASE refers to the class contain- 
ing the corrected element DISPLAY.BAS. The class that contained generation 9 of 
DISPLAY.BAS is not maintained. | 


. 
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Figure 6-4 : A CMS Class Containing a Superseded Element Generation 
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Chapter 7 


Additional CMS Commands 


This chapter describes the CMS ANNOTATE and CMS DIFFERENCES commands: 


e The CMS ANNOTATE command provides the history and line-by-line information 
about a library element. CMS lists the history of all changes ever made to the element 
and then lists each line of the element, tagging each line with the number of the gen- 
eration in which the line appears. CMS does not record an ANNOTATE operation in 
the library history. 


e The CMS DIFFERENCES command performs a line-by-line comparison of any two 
ASCII files. CMS does not record a DIFFERENCES operation in the library history. 


7.1 Getting Line-by-Line Information 


CMS maintains information about changes to each element in the library. The CMS 
ANNOTATE command produces a line-by-line listing of the changes made in any genera- 
tion of a specified element. The annotated listing begins with a summary of changes to the 
element (when it was modified, which generation was modified, and who did the modify- 
ing). Then, CMS lists the program and labels all lines that were not in the first generation. 
Each line that has been added (or changed) is marked with the generation number to indi- 
cate when the line was added or when it was last modified. The annotation process writes 
the listing in a file in your default directory. By default, CMS gives the file the same name 
as the element, but with a file type ANN. To annotate an earlier generation of the element, 

use the /GENERATION qualifier. 


When Sue Kelley wanted to see what modifications Rick Sanchez made to the element 
rTIMECVT.BAS, she used the following command: 


$ CMS ANNOTATE TIMECYT.BAS | 
ZCMS-S-ANNOTATED>s+ Element TIMECVT.BAS» generation 3 janeeted 


OMS delivered a file, TIMECVT.ANN, to Sue’s current default directory. Example 7-1 
shows the printed annotated output. The historical information at the top of the listing 
ndicates the user, date, time, and remark entered each time a new generation was cre- 
ated. The second entry of the history shows that Rick replaced a modified copy of 
TIMECVT.BAS, creating generation 2. The line-by-line information indicates that Rick 
nodified line 6. 


Example 7-1 shows a sample of the information delivered by the CMS ANNOTATE 


command. 


Annotated listings for element TIMECVT.BAS if DEC/CMS Litrary ORAS: CLEWIS.BCCMS} 


#3 25-MAR-1984 15:49:01 KELLEY “add check for invalid delta time” 


#2 25-MAR-1984 15:39:58 SANCHEZ “Jp - fined lensth string reauired"” 
#1} 25-MAR-1984 15:37:11 SANCHEZ “time conversion Program” 


Annotated listings for element TIMECYT.BAS in DEC/CMS Library DRAGS: {LEWIS.BCCNS] 


25-MAR-198d 


25-MAR-1984 


10 rem Program to compute an absolute time given the present time 


1 
Zz tem and a delta time. The result is written to a file. 
3 
a 20 OPTION TYPE = EXPLICIT 
> DECLARE STRING DELTA_TIME 
2 6 MAP (STRING_LEN) STRING ASC_TIME = 80 
7 DECLARE LONG RETCODE 
8 DIM LONG BINARY_DELTA‘(1) 
9 DIM LONG NOW(1) 
10 DIM LONG BINARY_CVUT_TIME(1) 
11 
12 100 EXTERNAL LONG CONSTANT SS$_NORMAL 
3 13 EXTERNAL LONG CONSTANT SS$_IVTIME 
14 EXTERNAL LONG FUNCTION LIBSADDX 
15 EXTERNAL LONG FUNCTION LIBSSUBX 
16 EXTERNAL LONG FUNCTION LIBSINT_OVER 
1? EXTERNAL LONG FUNCTION SYSSBINTIM (STRING BY DESC, LONG BY REF) 
i8 EXTERNAL LONG FUNCTION SYSSGETTIM (LONG BY REF) 
19 EXTERNAL LONG FUNCTION SYSSASCTIM (LONG BY REF; STRING BY DESCr & 
z0 LONG BY REF; LONG BY REF) 
z2! 150 LET RETCODE = LIBSINT_OVER(O) 
Z2 PRINT “Input delta time" 
23 INPUT DELTA_TIME : 
za LET RETCODE = SYSSBINTIM ( DELTA_TIME;+ BINARY_DELTA(Q) } 
a 25 175 IF (RETCODE = SS$_NORMAL) THEN GOTO 200 
3 26 ELSE IF RETCODE = SS$_IVTIME THEN & 
3 27 PRINT »"INVALID TIME" 
3 28 GOTO DONE 
3 293 END IF 
3 30 END IF 
3 31 200 LET RETCODE = SYS$GETTIM(NOW(O)) 
3 32 IF (VAL( DELTA_TIME ) > O ) THEN & 
33 RETCODE=LIBSADDX(NOW(O) +BINARY DELTA (0) sBINARY_CVT_TIME(0)) 
34 END IF 
35 LET RETCODE = SYSSASCTIM( -ASC_TIME »,BINARY_CVT_TIME(0) ;) 
36 OPEN “TIME.TMP“ FOR OUTPUT AS FILE #1 
37 PRINT #1,ASC_TIME 
38 CLOSE #1 
39 32767 Done: END 
46 


Example 7-1: Sample Annotated Listing 


7.2 Comparing Files 


Pera s | 


15:50:29 


The CMS DIFFERENCES command allows you to do line-by-line comparisons of two 
ASCII files. The files can exist in a CMS library or in a non-library directory. (If the files are 
in a CMS library, they must be in the same library; you cannot use CMS to compare ele- 


ments from different libraries.) 
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When CMS compares two files, it outputs a listing file to your default directory. By default, 
the listing file has the same name as the first file specified in the CMS DIFFERENCES 
command, with a file type of DIF. The file lists the names of the two files that were com- 
pared, and then lists all differing lines of the two files in sequential order with line num- 
bers and full line text. CMS DIFFERENCES does not generate an output file if the 
comparison does not result in any differences. 


On the data sampler project, Rick used the CMS DIFFERENCES command to check a bug 
fix. He compared the element generation that contained the bug against the next genera- 
tion by using the CMS DIFFERENCES command: 


$ CMS DIFFERENCES TIMECYVT.BAS /GENERATION=2 TIMECYT.BAS /GENERATION=1 
ZCMS-I-DIFFERENT,» files are different 


Rick used the /GENERATION qualifier to direct CMS to use generations 1 and 2 of 
TIMECVT.BAS in the comparison. Example 7-2 shows the report from this comparison, 
TIMECVT.DIF-. 


DEC/CMS File Comparison Utility 

Files Compared By SANCHEZ On 25-MAR-1984 15:51:58 
(1) Element TIMECVT.BAS Generation 2 
(2) Element TIMECVT.BAS Generation 1 


¥*¥#% Generation Differences **#*+* 


TIMECVT.BAS | 

3 25-MAR-1984 15:49:01 KELLEY “add check for invalid delta time" 
#2 25-MAR-1984 15:39:58 SANCHEZ "Jp - fixed length string required" 
*1 259-MAR-1984 15:37:11 SANCHEZ “time conversion Program" 


¥H2**% Text Differences **#** 


++ tee + te tt te t+ te te tt te te te t+ t+ te tteteeteete te tte tet + + t+ 
Element TIMECYT.BAS(2) Line 6 
1) MAP (STRING_LEN) STRING ASC_TIME = 80 


Element TIMECVT.BAS(1) Line 6 
2) DECLARE STRING ASC_TIME 


He*%* End of Differences *##* 
Example 7-2: Sample CMS DIFFERENCES Listing 


TIMECVT.DIF shows the element generations used in the comparison, the generation his- 
tory for the element, and the differences between the two generations. 
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Appendix A 


Kotes on Using CMS Libraries 


This appendix contains information that may be useful to you as you build and use your 
CMS library. In general, project planning will have the greatest impact on how you can 
best use CMS. Each project has its own characteristics that determine how you should 
organize it. 


The Library Storage Method 


CMS stores the entire text of the first generation of an element. Each time you replace an 
element, CMS determines what has been changed in the element file(s). In order to save 
storage space, only the new and changed lines of successive generations are stored. The 
rule of thumb for estimating online mass storage for the library is to allow three times the 
amount of space that you would normally allow for one copy of all project files. 


A file in a CMS library can be portrayed as shown in Example A-1. 


(152593) APPLES 
(1l92°3) BANANAS 
(19293) CHERRIES 

(1) POOCHES 

(2) PAUNCHES 

(3) PEACHES 

(19293) ELOERBERRIES 


Example A-1: The CMS Storage Method (Simplified) 


Example A-1 shows that each data item is numbered according to the element generations 
in which the item appears. The line “POOCHES” (occurring in the first generation) has 
been changed to “PAUNCHES” in the second generation, and changed again to 
“PEACHES?” in the third generation. 


CMS can provide a complete copy of any of the three generations whenever necessary. (It 
can also produce an annotated copy showing all changes in each generation and identify 
the person who made those changes.) However, in the library, the data require only seven 
lines of storage space. Conventional storage methods would require 15 lines, five lines for 
each of the three copies of the data. 


Project members do not have to keep back-up copies of CMS library files in their own 
account. Normal system backup procedures should be followed for the contents of a CMS 
library, as for any valuable files. CMS itself keeps a certain amount of back-up information 
to recover from an incomplete transaction after a system failure. 


Elements are stored most efficiently when modifications leave the majority of the file lines 
unchanged. CMS only stores one copy of an element; this copy includes all lines from the 
first generation plus all modifications to successive generations. Thus the number of dif- 
ferences (relative to the number of original lines) affects system efficiency. 


For example, the modifications to successive generations of a FORTRAN source program 
might typically change 15 to 20 percent of the lines during the development of that pro- 
gram. Since the bulk of the program does not change, this kind of element is ideal for a 
CMS library. On the other hand, the same program listing file would change drastically 
with each modification due to the compiler’s effect on line numbers, addresses, and so forth. 
Each generation of the stored listing element would contain almost as many differences as 
original lines. | 
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Glossary 


Class 
A set of element generations with only one generation per element. 
Concurrent replacement 


A library transaction that replaces an element that has been marked as concurrently 
reserved. 


Concurrent reservation 

Two or more reservations in effect for the same element at the same time. 
Element 

An ASCII file that is stored in a DEC/CMS library. 
Fetch 


Retrieves a copy of a library element that (in terms of library tracking) is for read- 
only purposes; the element is not reserved. 


Generation 


Representation of a phase in the development of an element: every time you retrieve 
and then return an element to the library (see Reservation and Replacement) a new 
generation is created. Any generation of an element can be retrieved; each genera- 
tion reflects the changes that were made at that particular point in development. 


Generation number 


A number or a combination of numbers and letter(s) that identify an element 
generation. 


Group 
A set of elements that can be manipulated as a unit. 
History 


The historical record of library access (generally includes all transactions except 
those that display library information or that access library contents for read-only 


purposes). 
Library 
The largest group of files that DEC/CMS recognizes as a unit. 


Glossary-1 


e of descent 


A series of generations of an element, created by successive reservation and replace- 
ment transactions. 


n line of descent 


The series of generations of an element that are identified by single generation 
numbers. 


‘ging | 
Combining two generations of an element that do not lie on the same line of descent. 
lacement 


A library transaction in which a user returns a reserved element to a library, thus 
ending the reservation. 


ervation 


A library transaction in which a user retrieves a copy of an element file from the 
library. DEC/CMS marks that library element as reserved by the user. For the dura- 
tion of the reservation, if any user reserves that element, CMS indicates that it is 
reserved. a 


iant generation 

An element generation that does not lie on the same line of descent as its predecessor. 
iant letter 

A letter used in a generation number to identify a variant line of descent. 
iant line of descent 


A line of descent that is separate from the main line of descent: an alternate develop- 
ment path. Generation numbers of variant line generations consist of combinations 
of numbers and variant letter(s). 


Glossary-2 


INDEX 


A 


Abbreviation, command, 1-4 
Access to library, 3-2 
Alternate development paths, 5-1 
.ANN file type, 7-1 
ANNOTATE, 7-1 
Annotated listing, 7-1 

sample, 7-2 
' ASCII file comparison, 7-2 


Back-up, library, A-1 
Base level, 6-4 


C 


Cancellation 
concurrent reservation, 5-9 
reservation, 3-3 
Class, 1-4 
creation, 6-5 
display, 6-7 
name, 6-5 
placement of generations in, 6-5 
reference by name, 6-7 
removal of a generation, 6-10 
replacement of generations, 6-10 
CMS, 1-1 
CMS capabilities, 1-1 
Code Management System, 1-1 


Combination of two penetrations, 5-4 
Command 
CREATE ELEMENT, 2-2 
CREATE LIBRARY, 2-2 
SET LIBRARY, 3-1 
Command abbreviation, 1-4 ses 
Command, CMS oo 
(see also individual subeananas dl 
names) 
CMS ANNOTATE, 7-1 
CMS CREATE CLASS, 6-5 
CMS CREATE GROUP, 6-3 
CMS DIFFERENCES, 7-2 
CMS FETCH, 3-5 
CMS INSERT ELEMENT, 6-3 
CMS INSERT GENERATION, 6-5 
CMS REMOVE ELEMENT, 6-3 
CMS REMOVE GENERATION, 6-10 
CMS REPLACE, 3-3 
CMS RESERVE, 3-2 
CMS SHOW, 4-1 
CMS SHOW CLASS, 6-7 
CMS SHOW ELEMENT, 4-1 
CMS SHOW GENERATION, 4-3 
CMS SHOW 
GENERATION/ANCESTORS, 4-3 
CMS SHOW 
GENERATION/DESCENDANTS, 
4-4 
CMS SHOW GROUP, 6-4 
CMS SHOW HISTORY, 4-2 
CMS SHOW LIBRARY, 3-2 
CMS SHOW RESERVATIONS, 4-2 
CMS UNRESERVE, 3-3 


Indexs1 


Comparison of ASCII files, 7-2 | Element (Cont.? 


Concurrent replacement, 5-9 removal from a group, 6-3 

Concurrent reservation, 5-7 i replacement, 3-3 
cancellation, 5-9 ar replacement with a fetched copy, 3-5 
record, 5-8 - reservation, 3-2 
replacement, 5-9 ’ VMS characteristics, 2-5 
warning, 5-7 

Conflict 
merge, 5-6 F 
resolution, 5-7 

/CONTENTS, 6-4, 6-7 ee 

CREATE (VMS command) File 


patentee A characteristics, 1-2 
CREATE CLASS, 6-5 a 
CREATE ELEMENT, 2-2 agents — 

CREATE GROUP, 6-3 aK oe 
CREATE LIBRARY, 2-2 | . DIF 7-3 
Creating a VMS library, 2-1 Files for the library, 2-5 


D = G 

DEC/CMS, 1-1 | /GENERATION, 3-2 

Definition of a release, 6-10 Generation 

-DIF file type, 7-3 combining, 5-4 

DIFFERENCES, 7-2 merging, 5-4 

Display, terminal | placement in a class, 6-5 
(see Terminal display) reference by class name, 6-7 


removal from a class, 6-10 
successive, 1-2 


E variant, 5-1 
Group, 1-4 
aac a creation, 6-3 
oe display, 6—4 
annotated listing, 7-1 oe so 


cancellation of a reservation, 3-3. - 
concurrent reservation, 5-7 
creation, 2-2 


removal of an element, 6-3 


definition, 2-2 Hi 

descendant, 4-4 

display list of, 4-1 HELP, 1-4 

generation of, 4-3 : History 

merging generations, 5—4 ANCESTORS, 4-3 
name, 2-2 | DESCENDANTS, 4-4 
read-only copy, 3-5 generation, 4-3 


Index-2 


Initializing a library, 2-2 

INSERT ELEMENT, 6-3 

INSERT GENERATION, 6-5 

INSERT GENERATION /ALWAYS, 
6-10 


K 


Keeping a reserved element, 3-4 
Kinds of files, 1-2, 2-5 


L 


Library 
back-up, A-1 
creation, 2-1 
evolution, 5-1 
history, 4-2 
history display, 4-2 
_ storage space, A-1 
Library directory 
Setting up 
VMS, 2-1 
Library information, terminal display, 
4—] a 
Line of descent 
main, 5-1, 5-3 
merging changes, 5-4 
variant, 5-1, 5-3 
Listing, annotated, 7-1 
LOGIN.COM, 3-2 


Main line of descent, 5-1, 5-3 
/MERGE, 5-4 
Merging generations, 5-4 

conflict, 5-6 

replacing a merged generation, 5-6 


N 


Name 
class, 6-5 
element, 2-2 
group, 6-3 


O 


Online documentation, 1-4 


p 


Placing files in library, 2-2~ ~~ ~ 
Project 
development stages, 1-4 
interaction, 6-1 
organization, 1-4, 6-1 
Protection : 
VMS library, 2-1 


4h 


Q _ 


Qualifier, CMS 
/ALWAYS, 6-10 
/CONTENTS, 6-4, 6-7 
/GENERATION, 3-2 
/MERGE, 5-4 
/RESERVE, 3-4 
/SINCE=date, 4-3 
/UNUSUAL, 5-8 
/VARIANT, 5-1 


Release 

definition, 6-10 
REMOVE ELEMENT, 6-3 - 
REMOVE GENERATION, 6-10 


Index-3 


REPLACE, 3-3 
/RESERVE, 3-4 
/VARIANT=x, 5-1 
Replacement 
concurrent, 5-9 
Replacement of a merged generation, 5-6 
Reservation 
cancellation, 3-3 
cancellation of a concurrent, 5-9 
concurrent, 5-7 Mo 
of a reserved element, 5-8 
Reservation of an element, 3-2 
/RESERVE, 3-4 
RESERVE, 3-2 
/GENERATION, 3-2 
/MERGE, 5-4 
Resolution of merge conflicts, 5-7 


S 


Sample terminal session, 1-3 
SET LIBRARY command, 3-1 
Setting up a library, 2-1 
SHOW, 4-1 
CLASS, 6-4, 6-7 
ELEMENT, 4-1 
GENERATION, 4-3 
HISTORY, 4-2 
HISTORY /SINCE=date, 4-3 
HISTORY /UNUSUAL, 5-8 
LIBRARY, 3-2 
RESERVATIONS, 4-2 
SHOW GENERATION 
ANCESTORS, 4-3 
DESCENDANTS, 4-4 
Specification of a generation, 3-2 
Stages of project development, 1-4 
Starting a CMS library, 2-1 
Storage space, A-1 | 
Successive generation, 1-2 


Index-4 


T 


Terminal display 
class, 6-7 
group, 6-4 
history, 4-2 
library elements, 4-1 
library information, 4-1. 
reservations, 4-2 
Trace | 
ancestors, 4-3 
descendants, 4-4 
Tracking a project, 6-1 
Typical CMS application, 1-5 


= 
& 


UNRESERVE, 3-3 
/UNUSUAL, 5-87 
Updating the history, 3-4 


V 


/VARIANT, 5-1 
Variant 
generation, 5-1 
letter, 5-1 
line of descent, 5-1, 5-3, 
variant of a, 5-2 


W 


Warning 
concurrent reservation, 5-7 
merge conflict, 5-6 


User’s Introduction to 
VAX DEC/CMS 
AA-L371B-TE 


Reader’s Comments 


Note: This form is for document comments only. DIGITAL will use comments 
submitted on this form at the company’s discretion. If you require a writ- 
ten reply and are eligible to receive one under Software Performance | 
Report (SPR) service, submit your comments on an SPR form. 


Did you find this manual understandable, usable, and well-organized? Please 
make suggestions for improvement. __ 


Did you find errors in this manual? If so, specify the error and the page number. a 





Please indicate the type of user/reader that you most nearly represent. : 
(1) Assembly language programmer 
(1 Higher-level language programmer - 
a 
[] Occasional programmer (experienced) 7 
(1 User with little programming experience 
[} Student programmer | 
[J Other (please specify) i 
IN YIN tO | 
Organization 
Street 
Na ee aS ae 


Country ~ 
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